/*
 * IPreconditioner.cs
 * 
 * Copyright (c) 2003-2004, dnAnalytics Project. All rights reserved.
*/

using dnAnalytics.LinearAlgebra;

namespace dnAnalytics.LinearAlgebra.Solvers.Preconditioners
{
    /// <summary>
    /// The base interface for preconditioner classes.
    /// </summary>
    /// <remarks>
    /// <para>
    /// Preconditioners are used by iterative solvers to improve the convergence
    /// speed of the solving process. Note that an increase in convergence speed
    /// is related to the number of iterations necessary to get a converged solution.
    /// So while in general the use of a preconditioner means that the iterative 
    /// solver will perform fewer iterations it does not guarantee that the actual
    /// solution time decreases given that some preconditioners can be expensive to 
    /// setup and run.
    /// </para>
    /// <para>
    /// Note that in general changes to the matrix will invalidate the preconditioner
    /// if the changes occur after creating the preconditioner.
    /// </para>
    /// </remarks>
    public interface IPreconditioner
    {
        /// <summary>
        /// Initializes the preconditioner and loads the internal data structures.
        /// </summary>
        void CreatePreconditioner();

        /// <summary>
        /// Solves the matrix equation <b>Ax = b</b>.
        /// </summary>
        /// <remarks>
        /// When using the <b>Solve</b> method consider carefully if the
        /// left hand side vector can be reused. If so it would be better to 
        /// use the overloaded <b>Solve</b> method.
        /// </remarks>
        /// <param name="vector">The right hand side vector.</param>
        /// <returns>The left hand side vector.</returns>
        Vector Solve(Vector vector);

        /// <summary>
        /// Solves the matrix equation <b>Ax = b</b>.
        /// </summary>
        /// <param name="vector">The right hand side vector.</param>
        /// <param name="result">The left hand side vector.</param>
        void Solve(Vector vector, Vector result);
    }
}
